/**
 * @file software_upgrade.c
 * @brief 软件升级数据模块实现
 * @details 本文件实现了104协议的软件升级数据处理功能，包括软件升级命令、
 *          软件升级状态、软件升级进度等数据类型的序列化和反序列化操作。
 *          支持完整的数据转换和验证功能。
 * 
 * @author zyb
 * @date 2025-10-17
 * @version 1.0
 * 
 * @note 所有函数都遵循104协议规范，确保严格的数据处理
 * @warning 数据转换失败时应返回相应的错误码，便于上层处理
 * 
 * @see software_upgrade.h
 * @see protocol_types.h
 * @see buffer_utils.h
 * @see time_utils.h
 */

#include "../include/software_upgrade.h"
#include "../../common/types/include/protocol_types.h"
#include "../../../../../common/utils/include/buffer_utils.h"
#include "../../common/utils/include/time_utils.h"
#include "../../common/error/include/error_codes.h"
#include "../../common/utils/include/validation_utils.h"
#include "../../../../../common/logs/include/logger.h"
#include <string.h>
#include <stdlib.h>

// 定义模块名称
#define LOG_MODULE_NAME "SOFTWARE_UPGRADE"

/* ==================== 软件升级命令处理函数实现 ==================== */

/**
 * @brief 软件升级命令转换为字节数组
 * @details 将软件升级命令结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param command 软件升级命令结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_ASDU_INVALID_ADDRESS: 地址无效
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_software_upgrade_command
 * @see validate_software_upgrade_command
 * @see buffer_write_u24
 * @see buffer_write_u8
 */
protocol_error_t software_upgrade_command_to_bytes(const F_SR_NA_1_t* command,
                                                 u8* buffer, u32 buffer_size, u32* actual_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换软件升级命令到字节数组: command=%p, buffer=%p, buffer_size=%u", 
              command, buffer, buffer_size);
    
    if (command == NULL || buffer == NULL || actual_length == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 验证软件升级命令 */
    LOG_DEBUG(LOG_MODULE_NAME, "验证信息对象地址: %u", command->info_address);
    if (!is_info_address_valid(command->info_address)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的信息对象地址: %u", command->info_address);
        return PROTOCOL_ERROR_ASDU_INVALID_ADDRESS;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "信息对象地址验证通过");
    
    LOG_DEBUG(LOG_MODULE_NAME, "验证软件升级命令类型");
    if (!is_software_upgrade_command_type_valid(&command->command_type)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级命令类型");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "软件升级命令类型验证通过");
    
    /* 检查缓冲区大小 */
    if (buffer_size < 4) { /* 地址(3字节) + 命令类型(1字节) */
        LOG_ERROR(LOG_MODULE_NAME, "缓冲区太小: %u < 4", buffer_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "缓冲区大小检查通过: %u >= 4", buffer_size);
    
    /* 写入信息对象地址 */
    LOG_DEBUG(LOG_MODULE_NAME, "写入信息对象地址: %u", command->info_address);
    buffer_write_u32(buffer, 0, command->info_address, 0);
    
    /* 写入命令类型 */
    LOG_DEBUG(LOG_MODULE_NAME, "写入命令类型: 0x%02X", *(u8*)&command->command_type);
    buffer[3] = *(u8*)&command->command_type;
    
    *actual_length = 4;
    LOG_INFO(LOG_MODULE_NAME, "软件升级命令成功转换为字节数组，实际长度: %u", *actual_length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 字节数组转换为软件升级命令
 * @details 将104协议规定的字节数组格式转换为软件升级命令结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param command 软件升级命令结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_ASDU_INVALID_ADDRESS: 地址无效
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳软件升级命令
 * 
 * @see software_upgrade_command_to_bytes
 * @see validate_software_upgrade_command
 * @see buffer_read_u24
 * @see buffer_read_u8
 */
protocol_error_t bytes_to_software_upgrade_command(const u8* data, u32 length,
                                                  F_SR_NA_1_t* command) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换字节数组到软件升级命令: data=%p, length=%u, command=%p", 
              data, length, command);
    
    if (data == NULL || command == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 检查数据长度 */
    if (length < 4) { /* 地址(3字节) + 命令类型(1字节) */
        LOG_ERROR(LOG_MODULE_NAME, "数据长度不足: %u < 4", length);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "数据长度检查通过: %u >= 4", length);
    
    /* 读取信息对象地址 */
    buffer_read_u32(data, 0, (u32*)&command->info_address, 0);
    LOG_DEBUG(LOG_MODULE_NAME, "读取信息对象地址: %u", command->info_address);
    
    /* 读取命令类型 */
    command->command_type = *(software_upgrade_command_type_t*)&data[3];
    LOG_DEBUG(LOG_MODULE_NAME, "读取命令类型: 0x%02X", *(u8*)&command->command_type);
    
    /* 验证转换后的数据 */
    if (!is_info_address_valid(command->info_address)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的信息对象地址: %u", command->info_address);
        return PROTOCOL_ERROR_ASDU_INVALID_ADDRESS;
    }
    
    if (!is_software_upgrade_command_type_valid(&command->command_type)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级命令类型");
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "字节数组成功转换为软件升级命令: info_address=%u, command_type=0x%02X", 
             command->info_address, *(u8*)&command->command_type);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 验证软件升级命令
 * @details 验证软件升级命令结构的完整性和有效性。
 *          检查地址和命令类型的有效性。
 * 
 * @param command 软件升级命令结构，不能为NULL
 * @return 验证结果
 *         - 1: 软件升级命令有效
 *         - 0: 软件升级命令无效
 * 
 * @note 验证地址和命令类型的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_info_address_valid
 * @see is_software_upgrade_command_type_valid
 * @see F_SR_NA_1_t
 */
int validate_software_upgrade_command(const F_SR_NA_1_t* command) {
    if (command == NULL) {
        return 0;
    }
    
    return (is_info_address_valid(command->info_address) && 
            is_software_upgrade_command_type_valid(&command->command_type));
}

/* ==================== 软件升级状态处理函数实现 ==================== */

/**
 * @brief 软件升级状态转换为字节数组
 * @details 将软件升级状态结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param status 软件升级状态结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_software_upgrade_status
 * @see validate_software_upgrade_status
 * @see buffer_write_u24
 * @see buffer_write_u8
 * @see buffer_write_u32
 */
protocol_error_t software_upgrade_status_to_bytes(const software_upgrade_status_info_t* status,
                                                u8* buffer, u32 buffer_size, u32* actual_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换软件升级状态到字节数组: status=%p, buffer=%p, buffer_size=%u", 
              status, buffer, buffer_size);
    
    if (status == NULL || buffer == NULL || actual_length == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 验证软件升级状态 */
    if (!is_info_address_valid(status->info_address)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的信息对象地址: %u", status->info_address);
        return PROTOCOL_ERROR_ASDU_INVALID_ADDRESS;
    }
    
    if (!is_software_upgrade_status_valid(status->status)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级状态: %u", status->status);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    if (!is_software_upgrade_stage_valid(status->stage)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级阶段: %u", status->stage);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "软件升级状态验证通过");
    
    /* 检查缓冲区大小 */
    if (buffer_size < 8) { /* 地址(3字节) + 状态(1字节) + 阶段(1字节) + 进度(1字节) + 错误码(2字节) */
        LOG_ERROR(LOG_MODULE_NAME, "缓冲区太小: %u < 8", buffer_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "缓冲区大小检查通过: %u >= 8", buffer_size);
    
    u32 offset = 0;
    
    /* 写入信息对象地址 */
    buffer_write_u32(&buffer[offset], 0, status->info_address, 0);
    offset += 3;
    LOG_DEBUG(LOG_MODULE_NAME, "写入信息对象地址: %u, 偏移: %u", status->info_address, offset);
    
    /* 写入状态 */
    buffer[offset] = (u8)status->status;
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "写入状态: %u, 偏移: %u", status->status, offset);
    
    /* 写入阶段 */
    buffer[offset] = (u8)status->stage;
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "写入阶段: %u, 偏移: %u", status->stage, offset);
    
    /* 写入进度 */
    buffer[offset] = status->progress;
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "写入进度: %u, 偏移: %u", status->progress, offset);
    
    /* 写入错误码 */
    buffer_write_u16(&buffer[offset], 0, status->error_code, 0);
    offset += 2;
    LOG_DEBUG(LOG_MODULE_NAME, "写入错误码: %u, 偏移: %u", status->error_code, offset);
    
    *actual_length = offset;
    LOG_INFO(LOG_MODULE_NAME, "软件升级状态成功转换为字节数组: info_address=%u, status=%u, stage=%u, actual_length=%u", 
             status->info_address, status->status, status->stage, *actual_length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 字节数组转换为软件升级状态
 * @details 将104协议规定的字节数组格式转换为软件升级状态结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param status 软件升级状态结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_ASDU_INVALID_ADDRESS: 地址无效
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳软件升级状态
 * 
 * @see software_upgrade_status_to_bytes
 * @see validate_software_upgrade_status
 * @see buffer_read_u24
 * @see buffer_read_u8
 * @see buffer_read_u16
 */
protocol_error_t bytes_to_software_upgrade_status(const u8* data, u32 length,
                                                 software_upgrade_status_info_t* status) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换字节数组到软件升级状态: data=%p, length=%u, status=%p", 
              data, length, status);
    
    if (data == NULL || status == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 检查数据长度 */
    if (length < 8) { /* 地址(3字节) + 状态(1字节) + 阶段(1字节) + 进度(1字节) + 错误码(2字节) */
        LOG_ERROR(LOG_MODULE_NAME, "数据长度不足: %u < 8", length);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "数据长度检查通过: %u >= 8", length);
    
    u32 offset = 0;
    
    /* 读取信息对象地址 */
    buffer_read_u32(&data[offset], 0, (u32*)&status->info_address, 0);
    offset += 3;
    LOG_DEBUG(LOG_MODULE_NAME, "读取信息对象地址: %u, 偏移: %u", status->info_address, offset);
    
    /* 读取状态 */
    status->status = (software_upgrade_status_t)data[offset];
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "读取状态: %u, 偏移: %u", status->status, offset);
    
    /* 读取阶段 */
    status->stage = (software_upgrade_phase_t)data[offset];
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "读取阶段: %u, 偏移: %u", status->stage, offset);
    
    /* 读取进度 */
    status->progress = data[offset];
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "读取进度: %u, 偏移: %u", status->progress, offset);
    
    /* 读取错误码 */
    buffer_read_u16(&data[offset], 0, &status->error_code, 0);
    offset += 2;
    LOG_DEBUG(LOG_MODULE_NAME, "读取错误码: %u, 偏移: %u", status->error_code, offset);
    
    /* 验证转换后的数据 */
    if (!is_info_address_valid(status->info_address)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的信息对象地址: %u", status->info_address);
        return PROTOCOL_ERROR_ASDU_INVALID_ADDRESS;
    }
    
    if (!is_software_upgrade_status_valid(status->status)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级状态: %u", status->status);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    if (!is_software_upgrade_stage_valid(status->stage)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级阶段: %u", status->stage);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "字节数组成功转换为软件升级状态: info_address=%u, status=%u, stage=%u, progress=%u", 
             status->info_address, status->status, status->stage, status->progress);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 验证软件升级状态
 * @details 验证软件升级状态结构的完整性和有效性。
 *          检查地址、状态、阶段、进度、错误码的有效性。
 * 
 * @param status 软件升级状态结构，不能为NULL
 * @return 验证结果
 *         - 1: 软件升级状态有效
 *         - 0: 软件升级状态无效
 * 
 * @note 验证地址、状态、阶段、进度、错误码的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_info_address_valid
 * @see is_software_upgrade_status_valid
 * @see is_software_upgrade_stage_valid
 * @see is_software_upgrade_progress_valid
 * @see is_software_upgrade_error_code_valid
 * @see software_upgrade_status_info_t
 */
int validate_software_upgrade_status(const software_upgrade_status_info_t* status) {
    if (status == NULL) {
        return 0;
    }
    
    return (is_info_address_valid(status->info_address) && 
            is_software_upgrade_status_valid(status->status) && 
            is_software_upgrade_stage_valid(status->stage) && 
            is_software_upgrade_progress_valid(status->progress) && 
            is_software_upgrade_error_code_valid(status->error_code));
}

/* ==================== 软件升级进度处理函数实现 ==================== */

/**
 * @brief 软件升级进度转换为字节数组
 * @details 将软件升级进度结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param progress 软件升级进度结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_software_upgrade_progress
 * @see validate_software_upgrade_progress
 * @see buffer_write_u24
 * @see buffer_write_u32
 * @see buffer_write_u8
 */
protocol_error_t software_upgrade_progress_to_bytes(const software_upgrade_progress_t* progress,
                                                  u8* buffer, u32 buffer_size, u32* actual_length) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换软件升级进度到字节数组: progress=%p, buffer=%p, buffer_size=%u", 
              progress, buffer, buffer_size);
    
    if (progress == NULL || buffer == NULL || actual_length == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 验证软件升级进度 */
    if (!is_info_address_valid(progress->info_address)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的信息对象地址: %u", progress->info_address);
        return PROTOCOL_ERROR_ASDU_INVALID_ADDRESS;
    }
    
    if (!is_software_upgrade_progress_valid(progress->progress_percent)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级进度: %u", progress->progress_percent);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    if (!is_software_upgrade_file_size_valid(progress->total_size)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级文件大小: %u", progress->total_size);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "软件升级进度验证通过");
    
    /* 检查缓冲区大小 */
    if (buffer_size < 8) { /* 地址(3字节) + 进度(1字节) + 总大小(4字节) */
        LOG_ERROR(LOG_MODULE_NAME, "缓冲区太小: %u < 8", buffer_size);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "缓冲区大小检查通过: %u >= 8", buffer_size);
    
    u32 offset = 0;
    
    /* 写入信息对象地址 */
    buffer_write_u32(&buffer[offset], 0, progress->info_address, 0);
    offset += 3;
    LOG_DEBUG(LOG_MODULE_NAME, "写入信息对象地址: %u, 偏移: %u", progress->info_address, offset);
    
    /* 写入进度百分比 */
    buffer[offset] = progress->progress_percent;
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "写入进度百分比: %u, 偏移: %u", progress->progress_percent, offset);
    
    /* 写入总大小 */
    buffer_write_u32(&buffer[offset], 0, progress->total_size, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "写入总大小: %u, 偏移: %u", progress->total_size, offset);
    
    *actual_length = offset;
    LOG_INFO(LOG_MODULE_NAME, "软件升级进度成功转换为字节数组: info_address=%u, progress_percent=%u, total_size=%u, actual_length=%u", 
             progress->info_address, progress->progress_percent, progress->total_size, *actual_length);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 字节数组转换为软件升级进度
 * @details 将104协议规定的字节数组格式转换为软件升级进度结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param progress 软件升级进度结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_ASDU_INVALID_ADDRESS: 地址无效
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳软件升级进度
 * 
 * @see software_upgrade_progress_to_bytes
 * @see validate_software_upgrade_progress
 * @see buffer_read_u24
 * @see buffer_read_u32
 * @see buffer_read_u8
 */
protocol_error_t bytes_to_software_upgrade_progress(const u8* data, u32 length,
                                                   software_upgrade_progress_t* progress) {
    LOG_DEBUG(LOG_MODULE_NAME, "转换字节数组到软件升级进度: data=%p, length=%u, progress=%p", 
              data, length, progress);
    
    if (data == NULL || progress == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "空指针参数错误");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    /* 检查数据长度 */
    if (length < 8) { /* 地址(3字节) + 进度(1字节) + 总大小(4字节) */
        LOG_ERROR(LOG_MODULE_NAME, "数据长度不足: %u < 8", length);
        return PROTOCOL_ERROR_BUFFER_TOO_SMALL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "数据长度检查通过: %u >= 8", length);
    
    u32 offset = 0;
    
    /* 读取信息对象地址 */
    buffer_read_u32(&data[offset], 0, (u32*)&progress->info_address, 0);
    offset += 3;
    LOG_DEBUG(LOG_MODULE_NAME, "读取信息对象地址: %u, 偏移: %u", progress->info_address, offset);
    
    /* 读取进度百分比 */
    progress->progress_percent = data[offset];
    offset += 1;
    LOG_DEBUG(LOG_MODULE_NAME, "读取进度百分比: %u, 偏移: %u", progress->progress_percent, offset);
    
    /* 读取总大小 */
    buffer_read_u32(&data[offset], 0, &progress->total_size, 0);
    offset += 4;
    LOG_DEBUG(LOG_MODULE_NAME, "读取总大小: %u, 偏移: %u", progress->total_size, offset);
    
    /* 验证转换后的数据 */
    if (!is_info_address_valid(progress->info_address)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的信息对象地址: %u", progress->info_address);
        return PROTOCOL_ERROR_ASDU_INVALID_ADDRESS;
    }
    
    if (!is_software_upgrade_progress_valid(progress->progress_percent)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级进度: %u", progress->progress_percent);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    if (!is_software_upgrade_file_size_valid(progress->total_size)) {
        LOG_ERROR(LOG_MODULE_NAME, "无效的软件升级文件大小: %u", progress->total_size);
        return PROTOCOL_ERROR_DATA_INVALID_VALUE;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "字节数组成功转换为软件升级进度: info_address=%u, progress_percent=%u, total_size=%u", 
             progress->info_address, progress->progress_percent, progress->total_size);
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 验证软件升级进度
 * @details 验证软件升级进度结构的完整性和有效性。
 *          检查地址、进度百分比、总大小、已传输大小的有效性。
 * 
 * @param progress 软件升级进度结构，不能为NULL
 * @return 验证结果
 *         - 1: 软件升级进度有效
 *         - 0: 软件升级进度无效
 * 
 * @note 验证地址、进度百分比、总大小、已传输大小的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_info_address_valid
 * @see is_software_upgrade_progress_valid
 * @see is_software_upgrade_file_size_valid
 * @see software_upgrade_progress_t
 */
int validate_software_upgrade_progress(const software_upgrade_progress_t* progress) {
    if (progress == NULL) {
        return 0;
    }
    
    return (is_info_address_valid(progress->info_address) && 
            is_software_upgrade_progress_valid(progress->progress_percent) && 
            is_software_upgrade_file_size_valid(progress->total_size));
}

/* ==================== 辅助函数实现 ==================== */

/**
 * @brief 获取软件升级命令大小
 * @details 获取软件升级命令结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @return 软件升级命令大小（字节）
 * 
 * @note 软件升级命令大小：4字节（地址3字节 + 命令类型1字节）
 * @warning 此函数是线程安全的
 * 
 * @see get_software_upgrade_status_size
 * @see get_software_upgrade_progress_size
 * @see F_SR_NA_1_t
 */
u32 get_software_upgrade_command_size(void) {
    return 4; /* 地址(3字节) + 命令类型(1字节) */
}

/**
 * @brief 获取软件升级状态大小
 * @details 获取软件升级状态结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @return 软件升级状态大小（字节）
 * 
 * @note 软件升级状态大小：8字节（地址3字节 + 状态1字节 + 阶段1字节 + 进度1字节 + 错误码2字节）
 * @warning 此函数是线程安全的
 * 
 * @see get_software_upgrade_command_size
 * @see get_software_upgrade_progress_size
 * @see software_upgrade_status_info_t
 */
u32 get_software_upgrade_status_size(void) {
    return 8; /* 地址(3字节) + 状态(1字节) + 阶段(1字节) + 进度(1字节) + 错误码(2字节) */
}

/**
 * @brief 获取软件升级进度大小
 * @details 获取软件升级进度结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @return 软件升级进度大小（字节）
 * 
 * @note 软件升级进度大小：12字节（地址3字节 + 进度1字节 + 总大小4字节 + 已传输大小4字节）
 * @warning 此函数是线程安全的
 * 
 * @see get_software_upgrade_command_size
 * @see get_software_upgrade_status_size
 * @see software_upgrade_progress_t
 */
u32 get_software_upgrade_progress_size(void) {
    return 12; /* 地址(3字节) + 进度(1字节) + 总大小(4字节) + 已传输大小(4字节) */
}

/* ==================== 软件升级状态处理函数实现 ==================== */

/**
 * @brief 获取软件升级状态名称
 * @details 根据软件升级状态枚举值获取对应的中文名称。
 *          用于调试和日志输出。
 * 
 * @param status 软件升级状态枚举值
 * @return 软件升级状态名称字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效状态返回"未知状态"
 * 
 * @see software_upgrade_status_t
 * @see get_software_upgrade_status_description
 */
const char* get_software_upgrade_status_name(software_upgrade_status_t status) {
    LOG_DEBUG(LOG_MODULE_NAME, "获取软件升级状态名称: status=%u", status);
    const char* name;
    
    switch (status) {
        case SOFTWARE_UPGRADE_STATUS_IDLE:
            name = "空闲状态";
            break;
        case SOFTWARE_UPGRADE_STATUS_STARTING:
            name = "启动中";
            break;
        case SOFTWARE_UPGRADE_STATUS_TRANSFERRING:
            name = "传输中";
            break;
        case SOFTWARE_UPGRADE_STATUS_INSTALLING:
            name = "安装中";
            break;
        case SOFTWARE_UPGRADE_STATUS_COMPLETED:
            name = "完成";
            break;
        case SOFTWARE_UPGRADE_STATUS_FAILED:
            name = "失败";
            break;
        case SOFTWARE_UPGRADE_STATUS_CANCELLED:
            name = "取消";
            break;
        default:
            name = "未知状态";
            break;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "软件升级状态名称: %s", name);
    return name;
}

/**
 * @brief 获取软件升级状态描述
 * @details 根据软件升级状态枚举值获取对应的详细描述。
 *          用于调试和日志输出。
 * 
 * @param status 软件升级状态枚举值
 * @return 软件升级状态描述字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效状态返回"未知状态"
 * 
 * @see software_upgrade_status_t
 * @see get_software_upgrade_status_name
 */
const char* get_software_upgrade_status_description(software_upgrade_status_t status) {
    switch (status) {
        case SOFTWARE_UPGRADE_STATUS_IDLE:
            return "软件升级处于空闲状态，等待命令";
        case SOFTWARE_UPGRADE_STATUS_STARTING:
            return "软件升级正在启动，准备开始升级";
        case SOFTWARE_UPGRADE_STATUS_TRANSFERRING:
            return "软件升级正在传输文件数据";
        case SOFTWARE_UPGRADE_STATUS_INSTALLING:
            return "软件升级正在安装软件包";
        case SOFTWARE_UPGRADE_STATUS_COMPLETED:
            return "软件升级成功完成";
        case SOFTWARE_UPGRADE_STATUS_FAILED:
            return "软件升级失败，需要检查错误";
        case SOFTWARE_UPGRADE_STATUS_CANCELLED:
            return "软件升级被取消";
        default:
            return "未知状态";
    }
}

/* ==================== 软件升级阶段处理函数实现 ==================== */

/**
 * @brief 获取软件升级阶段名称
 * @details 根据软件升级阶段枚举值获取对应的中文名称。
 *          用于调试和日志输出。
 * 
 * @param stage 软件升级阶段枚举值
 * @return 软件升级阶段名称字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效阶段返回"未知阶段"
 * 
 * @see software_upgrade_stage_t
 * @see get_software_upgrade_stage_description
 */
const char* get_software_upgrade_stage_name(software_upgrade_phase_t stage) {
    switch (stage) {
        case SOFTWARE_UPGRADE_PHASE_START:
            return "启动阶段";
        case SOFTWARE_UPGRADE_PHASE_TRANSFER:
            return "传输阶段";
        case SOFTWARE_UPGRADE_PHASE_INSTALL:
            return "安装阶段";
        case SOFTWARE_UPGRADE_PHASE_COMPLETE:
            return "完成阶段";
        case SOFTWARE_UPGRADE_PHASE_CANCEL:
            return "取消阶段";
        default:
            return "未知阶段";
    }
}

/**
 * @brief 获取软件升级阶段描述
 * @details 根据软件升级阶段枚举值获取对应的详细描述。
 *          用于调试和日志输出。
 * 
 * @param stage 软件升级阶段枚举值
 * @return 软件升级阶段描述字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效阶段返回"未知阶段"
 * 
 * @see software_upgrade_stage_t
 * @see get_software_upgrade_stage_name
 */
const char* get_software_upgrade_stage_description(software_upgrade_phase_t stage) {
    switch (stage) {
        case SOFTWARE_UPGRADE_PHASE_START:
            return "软件升级启动阶段，初始化升级环境";
        case SOFTWARE_UPGRADE_PHASE_TRANSFER:
            return "软件升级传输阶段，传输软件包";
        case SOFTWARE_UPGRADE_PHASE_INSTALL:
            return "软件升级安装阶段，安装软件包";
        case SOFTWARE_UPGRADE_PHASE_COMPLETE:
            return "软件升级完成阶段，升级完成";
        case SOFTWARE_UPGRADE_PHASE_CANCEL:
            return "软件升级取消阶段，升级被取消";
        default:
            return "未知阶段";
    }
}

/* ==================== 软件升级验证函数实现 ==================== */

/**
 * @brief 验证软件升级命令类型
 * @details 验证软件升级命令类型是否在有效范围内。
 *          检查保留位是否都为0。
 * 
 * @param command_type 软件升级命令类型
 * @return 验证结果
 *         - 1: 软件升级命令类型有效
 *         - 0: 软件升级命令类型无效
 * 
 * @note 软件升级命令类型只有1位有效，其他位必须为0
 * @warning 保留位必须为0
 * 
 * @see is_software_upgrade_status_valid
 * @see is_software_upgrade_stage_valid
 * @see software_upgrade_command_type_t
 */
int is_software_upgrade_command_type_valid(const software_upgrade_command_type_t* command_type) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证软件升级命令类型: command_type=%p", command_type);
    
    if (command_type == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "软件升级命令类型指针为空");
        return 0;
    }
    
    /* 软件升级命令类型只有1位有效，其他位必须为0 */
    int valid = (command_type->res == 0);
    LOG_INFO(LOG_MODULE_NAME, "软件升级命令类型验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证软件升级状态
 * @details 验证软件升级状态是否在有效范围内。
 *          软件升级状态范围：0-6
 * 
 * @param status 软件升级状态
 * @return 验证结果
 *         - 1: 软件升级状态有效
 *         - 0: 软件升级状态无效
 * 
 * @note 软件升级状态范围：0-6
 * @warning 软件升级状态不能为负数
 * 
 * @see is_software_upgrade_command_type_valid
 * @see is_software_upgrade_stage_valid
 * @see software_upgrade_status_t
 */
int is_software_upgrade_status_valid(software_upgrade_status_t status) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证软件升级状态: status=%u", status);
    int valid = (status >= SOFTWARE_UPGRADE_STATUS_IDLE && 
                 status <= SOFTWARE_UPGRADE_STATUS_CANCELLED);
    LOG_INFO(LOG_MODULE_NAME, "软件升级状态验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证软件升级阶段
 * @details 验证软件升级阶段是否在有效范围内。
 *          软件升级阶段范围：0-5
 * 
 * @param stage 软件升级阶段
 * @return 验证结果
 *         - 1: 软件升级阶段有效
 *         - 0: 软件升级阶段无效
 * 
 * @note 软件升级阶段范围：0-5
 * @warning 软件升级阶段不能为负数
 * 
 * @see is_software_upgrade_status_valid
 * @see is_software_upgrade_command_type_valid
 * @see software_upgrade_stage_t
 */
int is_software_upgrade_stage_valid(software_upgrade_phase_t stage) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证软件升级阶段: stage=%u", stage);
    int valid = (stage >= SOFTWARE_UPGRADE_PHASE_START && 
                 stage <= SOFTWARE_UPGRADE_PHASE_CANCEL);
    LOG_INFO(LOG_MODULE_NAME, "软件升级阶段验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证软件升级进度
 * @details 验证软件升级进度是否在有效范围内。
 *          软件升级进度范围：0-100
 * 
 * @param progress 软件升级进度
 * @return 验证结果
 *         - 1: 软件升级进度有效
 *         - 0: 软件升级进度无效
 * 
 * @note 软件升级进度范围：0-100
 * @warning 软件升级进度不能为负数或超过100
 * 
 * @see is_software_upgrade_file_size_valid
 * @see is_software_upgrade_error_code_valid
 */
int is_software_upgrade_progress_valid(u8 progress) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证软件升级进度: progress=%u", progress);
    int valid = (progress <= 100);
    LOG_INFO(LOG_MODULE_NAME, "软件升级进度验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证软件升级文件大小
 * @details 验证软件升级文件大小是否在有效范围内。
 *          软件升级文件大小范围：0-4294967295
 * 
 * @param file_size 软件升级文件大小
 * @return 验证结果
 *         - 1: 软件升级文件大小有效
 *         - 0: 软件升级文件大小无效
 * 
 * @note 软件升级文件大小范围：0-4294967295
 * @warning 软件升级文件大小不能为负数
 * 
 * @see is_software_upgrade_progress_valid
 * @see is_software_upgrade_error_code_valid
 */
int is_software_upgrade_file_size_valid(u32 file_size) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证软件升级文件大小: file_size=%u", file_size);
    int valid = (file_size <= 4294967295U);
    LOG_INFO(LOG_MODULE_NAME, "软件升级文件大小验证结果: %s", valid ? "有效" : "无效");
    return valid;
}

/**
 * @brief 验证软件升级错误码
 * @details 验证软件升级错误码是否在有效范围内。
 *          软件升级错误码范围：0-65535
 * 
 * @param error_code 软件升级错误码
 * @return 验证结果
 *         - 1: 软件升级错误码有效
 *         - 0: 软件升级错误码无效
 * 
 * @note 软件升级错误码范围：0-65535
 * @warning 软件升级错误码不能为负数
 * 
 * @see is_software_upgrade_progress_valid
 * @see is_software_upgrade_file_size_valid
 */
int is_software_upgrade_error_code_valid(u16 error_code) {
    LOG_DEBUG(LOG_MODULE_NAME, "验证软件升级错误码: error_code=%u", error_code);
    int valid = 1; // u16类型总是有效的
    LOG_INFO(LOG_MODULE_NAME, "软件升级错误码验证结果: %s", valid ? "有效" : "无效");
    return valid;
}
